<!DOCTYPE html>
<html lang="en">
<head>
	<meta charset="UTF-8">
	<meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
	<title>geo_shape(地理形状)数据类型 | ElasticSearch 7.7 权威指南中文版</title>
	<meta name="keywords" content="ElasticSearch 权威指南中文版, elasticsearch 7, es7, 实时数据分析，实时数据检索" />
    <meta name="description" content="ElasticSearch 权威指南中文版, elasticsearch 7, es7, 实时数据分析，实时数据检索" />
    <!-- Give IE8 a fighting chance -->
    <!--[if lt IE 9]>
    <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
    <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
    <![endif]-->
	<link rel="stylesheet" type="text/css" href="../static/styles.css" />
	<script>
	var _link = 'geo-shape.html';
    </script>
</head>
<body>
<div class="main-container">
    <section id="content">
        <div class="content-wrapper">
            <section id="guide" lang="zh_cn">
                <div class="container">
                    <div class="row">
                        <div class="col-xs-12 col-sm-8 col-md-8 guide-section">
                            <div style="color:gray; word-break: break-all; font-size:12px;">原英文版地址: <a href="https://www.elastic.co/guide/en/elasticsearch/reference/7.7/geo-shape.html" rel="nofollow" target="_blank">https://www.elastic.co/guide/en/elasticsearch/reference/7.7/geo-shape.html</a>, 原文档版权归 www.elastic.co 所有<br/>本地英文版地址: <a href="../en/geo-shape.html" rel="nofollow" target="_blank">../en/geo-shape.html</a></div>
                        <!-- start body -->
                  <div class="page_header">
<strong>重要</strong>: 此版本不会发布额外的bug修复或文档更新。最新信息请参考 <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/index.html" rel="nofollow">当前版本文档</a>。
</div>
<div id="content">
<div class="breadcrumbs">
<span class="breadcrumb-link"><a href="index.html">Elasticsearch 权威指南 [7.7]</a></span>
»
<span class="breadcrumb-link"><a href="mapping.html">映射</a></span>
»
<span class="breadcrumb-link"><a href="mapping-types.html">字段数据类型</a></span>
»
<span class="breadcrumb-node">geo_shape(地理形状)数据类型</span>
</div>
<div class="navheader">
<span class="prev">
<a href="geo-point.html">« geo_point(地理坐标点)数据类型</a>
</span>
<span class="next">
<a href="ip.html">IP 数据类型 »</a>
</span>
</div>
<div class="section">
<div class="titlepage"><div><div>
<h2 class="title">
<a id="geo-shape"></a>geo_shape(地理形状)数据类型
</h2>
</div></div></div>

<p>
<code class="literal">geo_shape</code>数据类型便于索引和搜索任意地理形状，如矩形和多边形。

当被索引的数据或被执行的查询包含形状而不仅仅是坐标点时，应该使用它。
</p>
<p>可以使用<a class="xref" href="query-dsl-geo-shape-query.html" title="Geo-shape query">geo_shape查询</a>来查询使用此类型的文档。</p>
<h4>
<a id="geo-shape-mapping-options"></a>映射之选项
</h4>
<p>
geo_shape 映射将 geo_json 几何对象映射到 geo_shape 类型。

要启用它，用户必须显式地将字段映射为 geo_shape 类型。
</p>
<div class="informaltable">
<table border="1" cellpadding="4px">
<colgroup>
<col class="col_1">
<col class="col_2">
<col class="col_3">
</colgroup>
<thead>
<tr>
<th align="left" valign="top">选项</th>
<th align="left" valign="top">描述</th>
<th align="left" valign="top">默认值</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left" valign="top"><p><code class="literal">tree</code></p></td>
<td align="left" valign="top"><p><span class="Admonishment Admonishment--change">
[<span class="Admonishment-version u-mono u-strikethrough">6.6</span>]
<span class="Admonishment-detail">
在6.6版本中废弃。不再使用 前缀树(PrefixTree)。
</span>
</span>
要使用的PrefixTree实现的名称：实现 GeohashPrefixTree 的是<code class="literal">geohash</code>，实现 QuadPrefixTree 的是<code class="literal">quadtree</code>。

注意：此参数仅与<code class="literal">term</code>(词项) 和 <code class="literal">recursive</code>(递归) 策略相关。
</p></td>
<td align="left" valign="top"><p><code class="literal">quadtree</code></p></td>
</tr>
<tr>
<td align="left" valign="top"><p><code class="literal">precision</code></p></td>
<td align="left" valign="top"><p><span class="Admonishment Admonishment--change">
[<span class="Admonishment-version u-mono u-strikethrough">6.6</span>]
<span class="Admonishment-detail">
在6.6版本中废弃。不再使用 前缀树(PrefixTree)。
</span>
</span>
可以使用此参数代替<code class="literal">tree_levels</code>来为<code class="literal">tree_levels</code>参数设置适当的值。

该值指定了所需的精度，Elasticsearch 将计算最佳的 tree_levels 值来满足该精度。

该值应当是后面跟可选距离单位的数字。

有效的距离单位包括：<code class="literal">in</code>、<code class="literal">inch</code>, <code class="literal">yd</code>、<code class="literal">yard</code>、<code class="literal">mi</code>、<code class="literal">miles</code>、<code class="literal">km</code>、<code class="literal">kilometers</code>、<code class="literal">m</code>、<code class="literal">meters</code>、<code class="literal">cm</code>、<code class="literal">centimeters</code>、<code class="literal">mm</code>、<code class="literal">millimeters</code>。

注意：此参数仅与<code class="literal">term</code>(词项) 和 <code class="literal">recursive</code>(递归) 策略相关。
</p>
</td>
<td align="left" valign="top"><p><code class="literal">50m</code></p></td>
</tr>
<tr>
<td align="left" valign="top"><p><code class="literal">tree_levels</code></p></td>
<td align="left" valign="top"><p><span class="Admonishment Admonishment--change">
[<span class="Admonishment-version u-mono u-strikethrough">6.6</span>]
<span class="Admonishment-detail">
在6.6版本中废弃。不再使用 前缀树(PrefixTree)。
</span>
</span>
PrefixTree 可以使用的最大层数。

这可以用来控制形状表示的精度，从而控制索引的词项的数量。

默认为所选的 PrefixTree 实现的默认值。

由于此参数需要对底层实现有一定程度的了解，因此用户可以使用<code class="literal">precision</code>参数代替之。

然而，Elasticsearch只在内部使用 tree_levels 参数，即使你使用了参数<code class="literal">precision</code>，这也是通过映射API返回的。

注意：此参数仅与<code class="literal">term</code>(词项) 和 <code class="literal">recursive</code>(递归) 策略相关。
</p></td>
<td align="left" valign="top"><p>various</p></td>
</tr>
<tr>
<td align="left" valign="top"><p><code class="literal">strategy</code></p></td>
<td align="left" valign="top"><p><span class="Admonishment Admonishment--change">
[<span class="Admonishment-version u-mono u-strikethrough">6.6</span>]
<span class="Admonishment-detail">
在6.6版本中废弃。不再使用 前缀树(PrefixTree)。
</span>
</span>
参数strategy定义了在编制索引和搜索时如何表示形状的方法。

它还会影响可用的功能，因此建议让 Elasticsearch 自动设置该参数。

有两种可用的参数：<code class="literal">recursive</code>和<code class="literal">term</code>。

recursive 和 term 策略已废弃，在未来的版本中将会删除。

虽然它们仍然可用，但 term 策略仅支持 point(坐标点) 类型(参数<code class="literal">points_only</code>将自动设置为 true)，而 recursive 策略支持所有 shape(形状) 类型。

(重要提示：有关这些策略的更多详细信息，请参考<a class="xref" href="geo-shape.html#prefix-trees" title="前缀树">前缀树</a>)
</p></td>
<td align="left" valign="top"><p><code class="literal">recursive</code></p></td>
</tr>
<tr>
<td align="left" valign="top"><p><code class="literal">distance_error_pct</code></p></td>
<td align="left" valign="top"><p><span class="Admonishment Admonishment--change">
[<span class="Admonishment-version u-mono u-strikethrough">6.6</span>]
<span class="Admonishment-detail">
在6.6版本中废弃。不再使用 前缀树(PrefixTree)。
</span>
</span>
用作 PrefixTree 的暗示，告诉它应该有多精确。

默认值为 0.025 (2.5%)，支持的最大值为 0.5。

性能说明：如果明确申明了<code class="literal">precision</code>或<code class="literal">tree_level</code>定义，该值将默认为 0。

这保证了映射中定义的空间精度。

这可能导致低误差的高分辨率形状占用大量内存(例如，1m 精度的大形状误差小于 0.001)。

为了提高索引性能(以牺牲查询精度为代价)，显式地定义<code class="literal">tree_level</code>或 <code class="literal">precision</code>，并使用合理的<code class="literal">distance_error_pct</code>，注意大的形状会有更大的误报。

注意：此参数仅与<code class="literal">term</code>(词项) 和 <code class="literal">recursive</code>(递归) 策略相关。
</p></td>
<td align="left" valign="top"><p><code class="literal">0.025</code></p></td>
</tr>
<tr>
<td align="left" valign="top"><p><code class="literal">orientation</code></p></td>
<td align="left" valign="top"><p>
选择性地定义如何解释多边形/多重多边形的顶点顺序。

该参数定义了两个坐标系规则(右手 right-hand 或左手 left-hand)中的一个，每一个都可以用三种不同的方式指定。

1. 右手(right-hand) 规则：<code class="literal">right</code>、<code class="literal">ccw</code>、<code class="literal">counterclockwise</code><span class="remark">(逆时针)</span>；

2. 左手(left-hand)规则：<code class="literal">left</code>、<code class="literal">cw</code>、<code class="literal">clockwise</code><span class="remark">(顺时针)</span>。

默认方向(<code class="literal">counterclockwise</code>，逆时针)符合 OGC 标准，该标准以逆时针顺序定义外环顶点，以顺时针顺序定义内环顶点(孔)。

在 geo_shape 映射中设置此参数会为 geo_shape 字段的坐标列表显式设置折点顺序，但可以被每个单独的 GeoJSON 或 WKT 文档所覆盖。
</p></td>
<td align="left" valign="top"><p><code class="literal">ccw</code></p></td>
</tr>
<tr>
<td align="left" valign="top"><p><code class="literal">points_only</code></p></td>
<td align="left" valign="top"><p><span class="Admonishment Admonishment--change">
[<span class="Admonishment-version u-mono u-strikethrough">6.6</span>]
<span class="Admonishment-detail">
在6.6版本中废弃。不再使用 前缀树(PrefixTree)。
</span>
</span>
将此选项设置为<code class="literal">true</code>(默认为<code class="literal">false</code>)将仅为 点(point) 形状配置 geo_shape 字段类型(注意：尚不支持多点)。

当已知只有点将被索引时，这优化了 <code class="literal">geohash</code> 和 <code class="literal">quadtree</code> 的索引编制和搜索性能。

目前，不能在<code class="literal">geo_point</code>类型的字段上执行 geo_shape 查询。

此选项通过提高<code class="literal">geo_shape</code>字段的点性能来弥补这一差距，从而使<code class="literal">geo_shape</code>查询在 "point only" 字段上达到最佳效果。
</p></td>
<td align="left" valign="top"><p><code class="literal">false</code></p></td>
</tr>
<tr>
<td align="left" valign="top"><p><code class="literal">ignore_malformed</code></p></td>
<td align="left" valign="top"><p>
如果为 true，则忽略格式错误的 GeoJSON 或 WKT 形状。

如果为 false(默认值)，格式错误的 GeoJSON 和 WKT 形状将导致异常并拒绝整个文档。
</p></td>
<td align="left" valign="top"><p><code class="literal">false</code></p></td>
</tr>
<tr>
<td align="left" valign="top"><p><code class="literal">ignore_z_value</code></p></td>
<td align="left" valign="top"><p>
如果为<code class="literal">true</code>(默认)，将接受三个维度点(存储在source中),但仅索引纬度(latitude)和经度(longitude)值；第三维度被忽略。

如果为<code class="literal">false</code>，包含任何超过纬度和经度(二维)值的地理坐标点将导致异常并拒绝整个文档。
</p></td>
<td align="left" valign="top"><p><code class="literal">true</code></p></td>
</tr>
<tr>
<td align="left" valign="top"><p><code class="literal">coerce</code></p></td>
<td align="left" valign="top"><p>如果为<code class="literal">true</code>，多边形中未闭合的线性环将自动闭合。</p></td>
<td align="left" valign="top"><p><code class="literal">false</code></p></td>
</tr>
</tbody>
</table>
</div>
<h4>
<a id="geoshape-indexing-approach"></a>编制索引的方法
</h4>
<p>
通过将形状分解成三角形网格并将每个三角形索引为 BKD 树中的 7 维点来索引 geo_shape 类型。

这提供了近乎完美的空间分辨率(低至1e<sup>-7</sup>十进制精度)，因为所有空间关系都是使用原始形状的编码矢量表示来计算的，而不是<a class="xref" href="geo-shape.html#prefix-trees" title="前缀树">前缀树(prefix trees)</a>索引方法所使用的光栅网格表示。

镶嵌器的性能主要取决于定义多边形/多多边形的顶点数量。

虽然这是默认的索引技术，但是仍然可以通过根据适当的<a class="xref" href="geo-shape.html#geo-shape-mapping-options" title="映射选项">M映射选项</a>设置<code class="literal">tree</code>或<code class="literal">strategy</code>参数来使用前缀树。

请注意，这些参数现在已被废弃，并将在未来版本中删除。
</p>
<p><span class="strong strong"><strong>重要提示</strong></span></p>
<p>
<code class="literal">CONTAINS</code>(包含) 关系查询 - 当使用新的默认向量索引策略时，使用7.5.0或更高版本的 ElasticSearch 创建的索引支持把<code class="literal">relation</code>定义为<code class="word">contains</code>的<code class="literal">geo_shape</code>查询。
</p>
<h4>
<a id="prefix-trees"></a>前缀树(prefix trees)
</h4>
<p><span class="Admonishment Admonishment--change">
[<span class="Admonishment-version u-mono u-strikethrough">6.6</span>]
<span class="Admonishment-detail">
在6.6版本中废弃。不再使用 前缀树(PrefixTree)。
</span>
</span>
为了在倒排索引中有效地表示形状，使用 PrefixTree (前缀树)的实现将形状转换为一系列表示网格正方形(通常称为 rasters, 即“栅格”)的哈希。

树的概念来自于 PrefixTree 使用多个网格层的事实，每个网格层都以越来越高的精度来表示 Earth(地球)。

这可以被认为是在更高的缩放级别下增加地图或图像的细节级别。

由于这种方法会导致索引的形状的精度问题，因此它已被弃用，取而代之的是将形状索引为三角形网格的矢量索引方法(参考<a class="xref" href="geo-shape.html#geoshape-indexing-approach" title="索引方法">索引方法</a>)。
</p>
<p>提供了多个 PrefixTree 实现方法：</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
GeohashPrefixTree：将<a href="http://en.wikipedia.org/wiki/Geohash" class="ulink" target="_top">geohash(地理哈希)</a>用于网格正方形。

geohash 是经纬度交织的 base32 编码的字符串。

添加到 geohash 的每个字符代表另一个树级别，并为 geohash 增加 5 比特位的精度。

geohash 表示一个矩形区域，有32个子矩形。

Elasticsearch中的最大级数为 24；默认值为 9。
</li>
<li class="listitem">
QuadPrefixTree：将<a href="http://en.wikipedia.org/wiki/Quadtree" class="ulink" target="_top">quadtree(四叉树)</a>用于网格正方形。

与 geohash 类似，quadtree(四叉树)交织纬度和经度的比特位，产生的哈希是一个比特位集。

四叉树中的树级别表示该比特位集中的 2 位，每个坐标一位。

Elasticsearch中四叉树的最大层数是 29；默认值为 21。
</li>
</ul>
</div>
<h5>
<a id="spatial-strategy"></a>空间策略
</h5>
<p><span class="Admonishment Admonishment--change">
[<span class="Admonishment-version u-mono u-strikethrough">6.6</span>]
<span class="Admonishment-detail">
在6.6版本中废弃。不再使用 前缀树(PrefixTree)。
</span>
</span>
所选择的索引实现方法依赖于选择如何分解形状(作为网格正方形或镶嵌的三角形网格)的空间策略。

每个策略回答以下问题：
</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
什么类型的形状可以被索引？
</li>
<li class="listitem">
可以使用哪些类型的查询操作和形状？
</li>
<li class="listitem">
它是否支持每个字段有多个形状？
</li>
</ul>
</div>
<p>提供了以下策略实现方法(具有相应的功能)：</p>
<div class="informaltable">
<table border="1" cellpadding="4px">
<colgroup>
<col class="col_1">
<col class="col_2">
<col class="col_3">
<col class="col_4">
</colgroup>
<thead>
<tr>
<th align="left" valign="top">策略</th>
<th align="left" valign="top">支持的形状</th>
<th align="left" valign="top">支持的查询</th>
<th align="left" valign="top">多形状</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left" valign="top"><p><code class="literal">recursive</code></p></td>
<td align="left" valign="top"><p><a class="xref" href="geo-shape.html#input-structure" title="Input Structure">所有</a></p></td>
<td align="left" valign="top"><p><code class="literal">INTERSECTS</code>、<code class="literal">DISJOINT</code>、<code class="literal">WITHIN</code>、<code class="literal">CONTAINS</code></p></td>
<td align="left" valign="top"><p>是</p></td>
</tr>
<tr>
<td align="left" valign="top"><p><code class="literal">term</code></p></td>
<td align="left" valign="top"><p><a class="xref" href="shape.html#point" title="点">点</a></p></td>
<td align="left" valign="top"><p><code class="literal">INTERSECTS</code></p></td>
<td align="left" valign="top"><p>是</p></td>
</tr>
</tbody>
</table>
</div>
<h5>
<a id="_accuracy"></a>精确度
</h5>
<p>
<code class="literal">recursive</code>和<code class="literal">term</code>策略不能提供100%的准确性，并且根据它们的配置方式，它可能会为<code class="literal">INTERSECTS</code>、<code class="literal">WITHIN</code>和<code class="literal">CONTAINS</code>查询返回一些假阳性，为<code class="literal">DISJOINT</code>查询返回一些假阴性。

为了减轻这种情况，为参数 tree_levels 选择一个合适的值并相应地调整期望值是很重要的。

例如，某个点可能靠近特定网格单元的边界，因此可能与仅匹配其旁边单元的查询不匹配，即使形状非常接近该点。
</p>
<h5>
<a id="_example_5"></a>示例
</h5>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT /index_name
{
    "mappings": {
        "properties": {
            "location": {
                "type": "geo_shape"
            }
        }
    }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/633.console"></div>
<p>
这个映射定义使用默认的矢量实现将 location 字段映射为 geo_shape 类型。

它提供大约 1e<sup>-7</sup>十进制的精度。
</p>
<h5>
<a id="_performance_considerations_with_prefix_trees"></a>前缀树(prefix tree)的性能考量
</h5>
<p><span class="Admonishment Admonishment--change">
[<span class="Admonishment-version u-mono u-strikethrough">6.6</span>]
<span class="Admonishment-detail">
在6.6版本中废弃。不再使用 前缀树(PrefixTree)。
</span>
</span>
使用前缀树，Elasticsearch 在倒排索引和查询中使用树中的路径作为词项。

级别越高(精度也越高)，生成的词项就越多。

当然，计算这些词项，将它们保存在内存中，以及将它们存储在磁盘上都是有代价的。

尤其是在树级别较高的情况下，即使数据量不多，索引也会变得非常大。

此外，特征的大小也很重要。

大而复杂的多边形会在较高的树级别上占用大量空间。

哪个设置是正确的取决于用例。

通常，人们会在准确性与索引大小和查询性能之间进行权衡。
</p>
<p>
对于这两种实现，Elasticsearch中的默认值是索引大小和赤道上50米的合理精度之间的折衷。

允许对数千万个形状进行索引，而不会使结果索引相对于输入大小过于膨胀。
</p>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>如果<a class="xref" href="query-dsl.html#query-dsl-allow-expensive-queries"><code class="literal">search.allow_expensive_queries</code></a>设置为 false，则不会对使用前缀树实现的地理形状执行 geo-shape 查询。</p>
</div>
</div>
<h4>
<a id="input-structure"></a>输入结构
</h4>
<p>
可以使用<a href="http://www.geojson.org" class="ulink" target="_top">GeoJSON</a>或<a href="http://docs.opengeospatial.org/is/12-063r5/12-063r5.html" class="ulink" target="_top">众所周知的文本</a> (WKT) 格式来表示形状。

下表提供了 GeoJSON 和 WKT 与 Elasticsearch 类型的映射：
</p>
<div class="informaltable">
<table border="1" cellpadding="4px">
<colgroup>
<col class="col_1">
<col class="col_2">
<col class="col_3">
<col class="col_4">
</colgroup>
<thead>
<tr>
<th align="left" valign="top">GeoJSON 类型</th>
<th align="left" valign="top">WKT 类型</th>
<th align="left" valign="top">Elasticsearch 类型</th>
<th align="left" valign="top">描述</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left" valign="top"><p><code class="literal">Point</code></p></td>
<td align="left" valign="top"><p><code class="literal">POINT</code></p></td>
<td align="left" valign="top"><p><code class="literal">point</code></p></td>
<td align="left" valign="top"><p>一个地理坐标。注意：Elasticsearch 仅使用 WGS-84 坐标。</p></td>
</tr>
<tr>
<td align="left" valign="top"><p><code class="literal">LineString</code></p></td>
<td align="left" valign="top"><p><code class="literal">LINESTRING</code></p></td>
<td align="left" valign="top"><p><code class="literal">linestring</code></p></td>
<td align="left" valign="top"><p>给定两点或多点的任意直线。</p></td>
</tr>
<tr>
<td align="left" valign="top"><p><code class="literal">Polygon</code></p></td>
<td align="left" valign="top"><p><code class="literal">POLYGON</code></p></td>
<td align="left" valign="top"><p><code class="literal">polygon</code></p></td>
<td align="left" valign="top"><p>
一个<em>闭合的</em>多边形，其第一个点和最后一个点必须匹配，因此需要<code class="literal">n + 1</code>个顶点来创建一个<code class="literal">n</code>边形和至少<code class="literal">4</code>个顶点。</p></td>
</tr>
<tr>
<td align="left" valign="top"><p><code class="literal">MultiPoint</code></p></td>
<td align="left" valign="top"><p><code class="literal">MULTIPOINT</code></p></td>
<td align="left" valign="top"><p><code class="literal">multipoint</code></p></td>
<td align="left" valign="top"><p>一组未连接但可能相关的点。</p></td>
</tr>
<tr>
<td align="left" valign="top"><p><code class="literal">MultiLineString</code></p></td>
<td align="left" valign="top"><p><code class="literal">MULTILINESTRING</code></p></td>
<td align="left" valign="top"><p><code class="literal">multilinestring</code></p></td>
<td align="left" valign="top"><p>一组独立的直线。</p></td>
</tr>
<tr>
<td align="left" valign="top"><p><code class="literal">MultiPolygon</code></p></td>
<td align="left" valign="top"><p><code class="literal">MULTIPOLYGON</code></p></td>
<td align="left" valign="top"><p><code class="literal">multipolygon</code></p></td>
<td align="left" valign="top"><p>一组独立的多边形。</p></td>
</tr>
<tr>
<td align="left" valign="top"><p><code class="literal">GeometryCollection</code></p></td>
<td align="left" valign="top"><p><code class="literal">GEOMETRYCOLLECTION</code></p></td>
<td align="left" valign="top"><p><code class="literal">geometrycollection</code></p></td>
<td align="left" valign="top"><p>类似于<code class="literal">multi*</code>形状的 GeoJSON 形状，只是多种类型可以共存(例如，Point 和 LineString)。</p></td>
</tr>
<tr>
<td align="left" valign="top"><p><code class="literal">N/A</code></p></td>
<td align="left" valign="top"><p><code class="literal">BBOX</code></p></td>
<td align="left" valign="top"><p><code class="literal">envelope</code></p></td>
<td align="left" valign="top"><p>通过仅指定左上角和右下角的点来指定的边界矩形或封套。</p></td>
</tr>
<tr>
<td align="left" valign="top"><p><code class="literal">N/A</code></p></td>
<td align="left" valign="top"><p><code class="literal">N/A</code></p></td>
<td align="left" valign="top"><p><code class="literal">circle</code></p></td>
<td align="left" valign="top"><p>由圆心和半径指定的圆，其单位默认为<code class="literal">METERS</code>。</p></td>
</tr>
</tbody>
</table>
</div>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>对于所有类型，内部<code class="literal">type</code>和<code class="literal">coordinates</code>(坐标)字段都是必需的。</p>
<p>
在 GeoJSON 和 WKT 以及 Elasticsearch 中，坐标数组中正确的<span class="strong strong"><strong>坐标顺序是经度(longitude)、纬度(latitude) (X，Y)</strong></span>。

这不同于许多地理空间API(例如Google Maps)，它们通常使用通俗的纬度、经度(Y，X)。
</p>
</div>
</div>
<h5>
<a id="geo-point-type"></a><a href="http://geojson.org/geojson-spec.html#id2" class="ulink" target="_top">Point</a>
</h5>
<p>
一个 point (点) 是一个地理坐标，比如一栋建筑的位置或者智能手机的 Geolocation API 给出的当前位置。

下面是 GeoJSON 中一个 point 的例子：
</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST /example/_doc
{
    "location" : {
        "type" : "point",
        "coordinates" : [-77.03653, 38.897676]
    }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/634.console"></div>
<p>下面是 WKT 中一个 point 的例子：</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST /example/_doc
{
    "location" : "POINT (-77.03653 38.897676)"
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/635.console"></div>
<h5>
<a id="geo-linestring"></a><a href="http://geojson.org/geojson-spec.html#id3" class="ulink" target="_top">LineString</a>
</h5>
<p>
由两个或多个位置的数组定义的<code class="literal">linestring</code>。

通过仅指定两个点，<code class="literal">linestring</code>将表示一条直线。

指定两个以上的点会创建任意路径。

下面是 GeoJSON 中一个 LineString 的例子：
</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST /example/_doc
{
    "location" : {
        "type" : "linestring",
        "coordinates" : [[-77.03653, 38.897676], [-77.009051, 38.889939]]
    }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/636.console"></div>
<p>下面是 WKT 中一个 LineString 的例子：</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST /example/_doc
{
    "location" : "LINESTRING (-77.03653 38.897676, -77.009051 38.889939)"
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/637.console"></div>
<p>上面的<code class="literal">linestring</code>将画一条从白宫到美国国会大厦的直线。</p>
<h5>
<a id="geo-polygon"></a><a href="http://www.geojson.org/geojson-spec.html#id4" class="ulink" target="_top">Polygon</a>
</h5>
<p>
多边形是由一系列点定义的。

每个(外部)列表中的第一个和最后一个点必须相同(多边形必须是闭合的)。

下面是 GeoJSON 中一个 Polygon 的例子：
</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST /example/_doc
{
    "location" : {
        "type" : "polygon",
        "coordinates" : [
            [ [100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0], [100.0, 0.0] ]
        ]
    }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/638.console"></div>
<p>下面是 WKT 中一个 Polygon 的例子：</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST /example/_doc
{
    "location" : "POLYGON ((100.0 0.0, 101.0 0.0, 101.0 1.0, 100.0 1.0, 100.0 0.0))"
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/639.console"></div>
<p>
第一个数组表示多边形的外部边界，其他数组表示内部形状(“孔”)。

下面是 GeoJSON 中一个有孔的 Polygon 的例子：
</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST /example/_doc
{
    "location" : {
        "type" : "polygon",
        "coordinates" : [
            [ [100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0], [100.0, 0.0] ],
            [ [100.2, 0.2], [100.8, 0.2], [100.8, 0.8], [100.2, 0.8], [100.2, 0.2] ]
        ]
    }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/640.console"></div>
<p>下面是 WKT 中一个有孔的 Polygon 的例子：</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST /example/_doc
{
    "location" : "POLYGON ((100.0 0.0, 101.0 0.0, 101.0 1.0, 100.0 1.0, 100.0 0.0), (100.2 0.2, 100.8 0.2, 100.8 0.8, 100.2 0.8, 100.2 0.2))"
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/641.console"></div>
<p>
<span class="strong strong"><strong>重要提示：</strong></span>WKT 没有强制顶点的特定顺序，因此日期变更线和极点周围的多边形可能不明确。

<a href="https://tools.ietf.org/html/rfc7946#section-3.1.6" class="ulink" target="_top">GeoJSON</a>要求外部多边形必须为逆时针方向，内部形状必须为顺时针方向，这符合开放地理空间联盟(Open Geospatial Consortium，OGC)关于顶点排序的<a href="http://www.opengeospatial.org/standards/sfa" class="ulink" target="_top">简单特性访问</a>规范。
</p>
<p>
如果顺时针和逆时针多边形看起来没有穿过日期变更线(即，它们穿过的经度小于180°)，则 Elasticsearch 接受这两种多边形，但对于穿过日期变更线的多边形(或宽度大于180°的其他多边形), Elasticsearch 要求顶点排序符合 OGC 和 GeoJSON 规范。

否则，可能会创建非预期的多边形，并会返回意外的查询/过滤结果。
</p>
<p>
下面提供了一个不明确多边形的示例。

Elasticsearch 将应用 GeoJSON 标准来消除导致与日期变更线相交的多边形的模糊性。
</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST /example/_doc
{
    "location" : {
        "type" : "polygon",
        "coordinates" : [
            [ [-177.0, 10.0], [176.0, 15.0], [172.0, 0.0], [176.0, -15.0], [-177.0, -10.0], [-177.0, 10.0] ],
            [ [178.2, 8.2], [-178.8, 8.2], [-180.8, -8.8], [178.2, 8.8] ]
        ]
    }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/642.console"></div>
<p>
设置 geo_shape 映射时，可以定义一个参数<code class="literal">orientation</code>(请参见<a class="xref" href="geo-shape.html#geo-shape-mapping-options" title="Mapping Options">映射选项</a>)。

这将为映射的 geo_shape 字段上的坐标列表定义顶点顺序。

它也可以在每个文档上被覆盖。

以下是一个覆盖文档上的方向的示例：
</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST /example/_doc
{
    "location" : {
        "type" : "polygon",
        "orientation" : "clockwise",
        "coordinates" : [
            [ [100.0, 0.0], [100.0, 1.0], [101.0, 1.0], [101.0, 0.0], [100.0, 0.0] ]
        ]
    }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/643.console"></div>
<h5>
<a id="geo-multipoint"></a><a href="http://www.geojson.org/geojson-spec.html#id5" class="ulink" target="_top">MultiPoint</a>
</h5>
<p>下面是一个 GeoJSON 格式 point 列表的示例：</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST /example/_doc
{
    "location" : {
        "type" : "multipoint",
        "coordinates" : [
            [102.0, 2.0], [103.0, 2.0]
        ]
    }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/644.console"></div>
<p>下面是一个 WKT 格式 point 列表的示例：</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST /example/_doc
{
    "location" : "MULTIPOINT (102.0 2.0, 103.0 2.0)"
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/645.console"></div>
<h5>
<a id="geo-multilinestring"></a><a href="http://www.geojson.org/geojson-spec.html#id6" class="ulink" target="_top">MultiLineString</a>
</h5>
<p>下面是一个 GeoJSON 格式 linestring 列表的示例：</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST /example/_doc
{
    "location" : {
        "type" : "multilinestring",
        "coordinates" : [
            [ [102.0, 2.0], [103.0, 2.0], [103.0, 3.0], [102.0, 3.0] ],
            [ [100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0] ],
            [ [100.2, 0.2], [100.8, 0.2], [100.8, 0.8], [100.2, 0.8] ]
        ]
    }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/646.console"></div>
<p>下面是一个 WKT 格式 linestring 列表的示例：</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST /example/_doc
{
    "location" : "MULTILINESTRING ((102.0 2.0, 103.0 2.0, 103.0 3.0, 102.0 3.0), (100.0 0.0, 101.0 0.0, 101.0 1.0, 100.0 1.0), (100.2 0.2, 100.8 0.2, 100.8 0.8, 100.2 0.8))"
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/647.console"></div>
<h5>
<a id="geo-multipolygon"></a><a href="http://www.geojson.org/geojson-spec.html#id7" class="ulink" target="_top">MultiPolygon</a>
</h5>
<p>下面是一个 GeoJSON 格式 polygon 列表的示例(第二个多边形包含一个孔)：</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST /example/_doc
{
    "location" : {
        "type" : "multipolygon",
        "coordinates" : [
            [ [[102.0, 2.0], [103.0, 2.0], [103.0, 3.0], [102.0, 3.0], [102.0, 2.0]] ],
            [ [[100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0], [100.0, 0.0]],
              [[100.2, 0.2], [100.8, 0.2], [100.8, 0.8], [100.2, 0.8], [100.2, 0.2]] ]
        ]
    }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/648.console"></div>
<p>下面是一个 WKT 格式 polygon 列表的示例(第二个多边形包含一个孔)：</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST /example/_doc
{
    "location" : "MULTIPOLYGON (((102.0 2.0, 103.0 2.0, 103.0 3.0, 102.0 3.0, 102.0 2.0)), ((100.0 0.0, 101.0 0.0, 101.0 1.0, 100.0 1.0, 100.0 0.0), (100.2 0.2, 100.8 0.2, 100.8 0.8, 100.2 0.8, 100.2 0.2)))"
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/649.console"></div>
<h5>
<a id="geo-geometry_collection"></a><a href="http://geojson.org/geojson-spec.html#geometrycollection" class="ulink" target="_top">Geometry Collection</a>
</h5>
<p>下面是一个 GeoJSON 格式 几何对象集合的示例：</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST /example/_doc
{
    "location" : {
        "type": "geometrycollection",
        "geometries": [
            {
                "type": "point",
                "coordinates": [100.0, 0.0]
            },
            {
                "type": "linestring",
                "coordinates": [ [101.0, 0.0], [102.0, 1.0] ]
            }
        ]
    }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/650.console"></div>
<p>下面是一个 WKT 格式 几何对象集合的示例：</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST /example/_doc
{
    "location" : "GEOMETRYCOLLECTION (POINT (100.0 0.0), LINESTRING (101.0 0.0, 102.0 1.0))"
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/651.console"></div>
<h5>
<a id="_envelope"></a>envelope (边界矩形)
</h5>
<p>Elasticsearch 支持一种<code class="literal">envelope</code>类型，它由形状的左上角和右下角的坐标组成，以<code class="literal">[[minLon, maxLat], [maxLon, minLat]]</code>格式表示一个边界矩形：</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST /example/_doc
{
    "location" : {
        "type" : "envelope",
        "coordinates" : [ [100.0, 1.0], [101.0, 0.0] ]
    }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/652.console"></div>
<p>以下是使用 WKT BBOX 格式的 envelope 的示例: </p>
<p>

<span class="strong strong"><strong>注意：</strong></span> WKT规范要求以下顺序：minLon，maxLon，maxLat，minLat。
</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST /example/_doc
{
    "location" : "BBOX (100.0, 102.0, 2.0, 0.0)"
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/653.console"></div>
<h5>
<a id="_circle"></a>circle (圆形)
</h5>
<p>
Elasticsearch 支持一种<code class="literal">circle</code>类型，由一个中心点和一个半径组成。

注意，只有在 前缀树(prefix tree) 使用<code class="literal">recursive</code>策略时，才能对这个圆的表示进行索引。

对于默认的<a class="xref" href="geo-shape.html#geoshape-indexing-approach" title="索引方法">索引方法</a>，circle 应该使用<code class="literal">POLYGON</code>来近似表示。
</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST /example/_doc
{
    "location" : {
        "type" : "circle",
        "coordinates" : [101.0, 1.0],
        "radius" : "100m"
    }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/654.console"></div>
<p>
注意：内 <code class="literal">radius</code>(半径) 字段是必需的。

如果半径的数值后面没有指定单位，那么半径的单位将默认为<code class="literal">METERS</code>。
</p>
<p>
注意:GeoJSON和WKT都不支持点半径圆类型。

<span class="strong strong"><strong>注意：</strong></span> GeoJSON 和 WKT 都不支持 point-radius circle 类型。
</p>
<h4>
<a id="_sorting_and_retrieving_index_shapes"></a>排序和检索索引形状
</h4>
<p>
由于形状的复杂的输入结构和索引表示，目前无法对形状进行排序或直接检索它们的字段。

geo_shape 值只能通过<code class="literal">_source</code>字段检索。
</p>
</div>
<div class="navfooter">
<span class="prev">
<a href="geo-point.html">« geo_point(地理坐标点)数据类型</a>
</span>
<span class="next">
<a href="ip.html">IP 数据类型 »</a>
</span>
</div>
</div>

                  <!-- end body -->
                        </div>
                        <div class="col-xs-12 col-sm-4 col-md-4" id="right_col">
                        
                        </div>
                    </div>
                </div>
            </section>
        </div>
    </section>
</div>
<script src="../static/cn.js"></script>
</body>
</html>